home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / qbbs / raecc011.zip / RAECC011.DOC < prev    next >
Text File  |  1990-06-23  |  19KB  |  440 lines
  1. RAECC: Remote Access Embedded Code Compiler - Beta Version 0.11               |
  2. Copyright (C) 1990 by David B. Thompson.
  3.  
  4.  
  5. WHAT IS IT?
  6. -----------
  7.  
  8. RAECC and RAECU are a pair of programs for creating and maintaining text
  9. files used to run a Remote Access bulletin board system.  RAECC "compiles"
  10. Remote Access embedded codes (used to display system and user
  11. information) and ANSI color and screen control codes from keywords (listed
  12. below).  The resulting files may be used as menus (using an auto-executed
  13. type 40 command) or simply displayed as text files containing user or
  14. system information (using a type 5, 40 or 45 command).  RAECU reverses the
  15. process, that is, it produces a file containing keywords translated from
  16. the embedded codes and ANSI escape sequences, plus any text contained in
  17. the file.
  18.  
  19. Although this software is being released as a beta, it is probably more of    |
  20. a gamma version.  I have found few bugs in the software, a none have been     |
  21. reported to me as of this release date.  As Remote Access matures and         |
  22. development slows, I will update the version number to 1.0 and call this      |
  23. software release quality.                                                     |
  24.  
  25.  
  26. LICENSE:                                                                      |
  27. --------                                                                      |
  28.  
  29. This is a shareware program.  Sysops (the intended audience) are welcome to   |
  30. use this program without compensation, but contributions not to exceed        |
  31. $5.00 are welcome.  Let your conscience be your guide.  All monies will be    |
  32. used to support my BBS.  In any event, please distribute this program by      |
  33. sharing it through bulletin board systems or other means.                     |
  34.  
  35. If you are a user residing outside the United States, please send me a
  36. postcard of your town or surrounding countryside.  I got this idea from
  37. Stig Jacobsen (author of FileDoor) and think it is really neat!  I'm sure
  38. my kids will appreciate cards from around the world <grin>!
  39.  
  40. Under no circumstances is the program to be distributed for a fee (this 
  41. includes public domain libraries that charge "copying costs" for software 
  42. distribution) without prior arrangements with the author.  Bulletin board 
  43. systems which charge a fee for normal access may distribute this program.  
  44. Similarly, no modified version of the program may be distributed.  Finally, 
  45. do not distribute the software under any name but RAECC???.(ZIP ARC LZH or
  46. whatever), that is, you may rearchive the software, but do not change the 
  47. name or version number. 
  48.  
  49.  
  50. DISCLAIMER:
  51. -----------
  52.  
  53. This program is warranted to do nothing.  In using this program, you accept
  54. complete responsibility for anything that happens to your system and agree
  55. to release me from any and all liability.  Every effort has been made to
  56. provide bug-free software, but there is no warranty as to suitability,
  57. merchantability or functionality.
  58.  
  59.  
  60. PAYMENT:
  61. --------
  62.  
  63. Contributions for the software may be directed to:
  64.  
  65.                                BrainStorm BBS 
  66.                            c/o David B. Thompson
  67.                                204 Brookdale
  68.                           Carriere, MS  39426  USA
  69.  
  70.  
  71. AVAILABILITY:
  72. -------------
  73.  
  74. The current version of the program is always available for File Request
  75. from my system (Fidonet 1:18/60).  I also happen to know that Mark Howard
  76. keeps a copy on Rivendel (Fidonet 1:260/340).  You will probably find
  77. other systems where it is used as well.
  78.  
  79.  
  80. RAECC PROGRAM USE:
  81. ------------------
  82.  
  83. Use of RAECC is very simple.  At the command line, enter the following
  84. command: 
  85.  
  86.                    RAECC Input.Rac Output.A?? /a /o                           |
  87.  
  88. where:                                                                        |
  89.         Input.Rac  is the file containing RA and ANSI keywords.               |
  90.         Output.Rac is the file containing RA and/or ANSI control codes.       |
  91.         /a         is a switch that enables generation of ANSI codes.         |
  92.         /o         is a switch that enables automatic overwriting of          |
  93.                    and existing output file.                                  |
  94.  
  95. The file, input.rac, contains text and command keywords you provide.  The     |
  96. file output.a?? contains your text, with RA embedded command codes and
  97. ANSI color or screen control codes.  Maximum line length of the input and 
  98. output files is 255 characters.  The number of lines in the file is 
  99. unlimited.
  100.  
  101. The /a is a switch that turns on generation of ANSI color and screen
  102. control codes.  If you don't specify the ANSI switch, then ANSI keywords
  103. are ignored and are not placed in the output file.  In this case,
  104. straight ASCII text will be passed through, with the substitution of the
  105. RA control codes for appropriate keywords.  Note that you should not
  106. embed ANSI characters in a *.ASC file because RA sends *.ASC files to
  107. users who do not use ANSI.SYS.  Be forewarned, you'll get lots of grief
  108. from your users if you make this mistake!
  109.  
  110. The /o switch turns overwrite mode on.  Be careful, because the program
  111. won't ask you if it's acceptable to write over an existing output file.
  112. The purpose of this switch is to allow you to construct a make file for
  113. all your text files.
  114.  
  115.  
  116. If you don't enter the names on the command line, then you will prompted 
  117. for them.  If you should specify the same filename for both input and 
  118. output, you will be warned and program execution will cease. 
  119.  
  120. All commands are delineated by placing them in brackets '[' and ']'.  No 
  121. spaces are allowed between the brackets and the command text.  Unmatched 
  122. brackets are not filtered, but passed through the program as is. 
  123. Unrecognized commands are also passed through the program.  The program is 
  124. not case sensitive. 
  125.  
  126.  
  127. RAECU PROGRAM USE:
  128. ------------------
  129.  
  130. To decompile a text file, enter:
  131.  
  132.                    RAECU Input.A?? Output.Rac                                 |
  133.  
  134. The file, Output.Rac, will contain the RA keywords and ANSI keywords          |
  135. corresponding to the codes found in the input.a?? file.  You may modify       |
  136. the file and recompile the file using RAECC.                                  |
  137.  
  138.  
  139. WARNING:                                                                      |
  140. --------                                                                      |
  141.  
  142. Be careful when decompiling ASC files.  If you have an existing .rac          |
  143. file which contains ANSI keywords and decompile a .ASC file and               |
  144. overwrite it, then your ANSI keywords will be lost!  You get a chance to      |
  145. abort an overwrite, but you should still be careful.  (A backup of your       |
  146. .rac files is probably an *EXCELLENT* idea!  I recommend that you use one     |
  147. of the archiving utilities for this purpose.  This makes small files and
  148. easy updates.)
  149.  
  150.  
  151. EXAMPLES:
  152. ---------
  153.  
  154. In the file RAECCTST.RAC, you will find my test file, uncompiled.  This
  155. file is provided to give you an example to follow.  You can (and should)
  156. play with this a little to give you a feel for how the compiler and
  157. decompiler work.
  158.  
  159. If you use a MAKE utility for programming purposes, you can set up a
  160. dependency file for RAECC, and maintain your text files and menus very
  161. easily.  This is probably one of the most powerful ways to apply RAECC.
  162.  
  163.  
  164. COMMAND LIST (from RA version 0.04):                                          |
  165. --------------------------------------
  166.  
  167.  RA
  168. Command       Meaning
  169. -------       -------
  170.  
  171. PAUSE         Pause and wait for Enter.
  172. ABORTOFF      Turn 'S' aborts off.
  173. ABORTON       Turn 'S' aborts on.
  174. MOREON        Turn 'more' on.
  175. MOREOFF       Turn 'more' off.
  176. BELL          Ring the user's bell.
  177. CLS           Clear the screen.
  178. WAIT          Pause for one second.
  179. SHELL         Run a program under a DOS shell.
  180. USERNAME      Display full user name.
  181. CITYSTAT      Display user's city and state.
  182. PASSWORD      Display user's password.
  183. BUSPHONE      Display user's business/data phone number.
  184. HOMPHONE      Display usre's home/voice phone number.
  185. LASTDATE      User's last logon date.
  186. LASTTIME      User's last logon time.
  187. AFLAGS        Display user's A flags.
  188. BFLAGS        Display user's B flags.
  189. CFLAGS        Display user's C flags.
  190. DFLAGS        Display user's D flags.
  191. CREDIT        Display user's net mail credit.
  192. POSTS         User's number of message posts.
  193. MESSREAD      Display user's high read message.
  194. SECLVL        Display user's security level.
  195. LOGONS        User's number of times logged on.
  196. UPLOADS       User's number of uploads.
  197. UPLDK         User's uploads in Kbytes.
  198. DNLOADS       User's number of downloads.
  199. DNLDK         User's downloads in Kbytes.
  200. ELAPTIME      Display time used this call.
  201. SCNLGTH       Display user's screen length.
  202. FNAME         User's first name.
  203. ANSI          Show the state of the ANSI graphics toggle.
  204. MORE          Show the state of the more toggle.
  205. SCNCLR        Show the state of the screen clear codes toggle.
  206. FSED          Display full-screen editor on/off.
  207. QUIET         Do not disturb mode.
  208. HOTKEYS       Display hotkeys on or off.
  209. CALLS         Display number of calls on the system.
  210. LASTCALL      Display last caller's name.
  211. ACTMESS       Show number of active messages.
  212. LOWMESS       Display low message number.
  213. HIGHMESS      Display high message number.
  214. PAGES         Display the number of sysop pages the user has made.
  215. FULLDOW       Show the full day-of-week.
  216. NOUSERS       Display the total number of users.
  217. TIME24        Display current time in 24hr format.
  218. DATE          Display current date.
  219. CONMIN        Show user's minutes of connect time.
  220. CONSEC        Show user's seconds of connect time (fractional minutes).
  221. MINUSED       Display user's number of minutes used.
  222. SECUSED       Display user's number of seconds used.
  223. MINREM        Show user's remaining minutes.
  224. SECREM        Show user's remaining seconds.
  225. TIMELIM       Show user's time daily time limit.
  226. BAUD          Display user's current baud rate.
  227. ABDOW         Display abbreviated day-of-week.
  228. DNLIMIT       Show user's download limit (for the day).
  229. TILEVENT      Display number of minutes until the next system event.
  230. TIMEVENT      Display the time of the next system event.
  231. LINENO        Line numbers (as set on command line).  (It sure beats me what
  232.               this means!)
  233. TERMINAT      End current call.
  234. CURMNAME      Name of the current template message area.                      |
  235. CURFNAME      Name of the current template file area.                         |
  236. CURNMSGS      Number of messages in selected message area.                    |
  237. CURMAREA      Number of current template message area.                        |
  238. CURFAREA      Number of current template file area.                           |
  239.  
  240.  
  241.  ANSI
  242. Command       Meaning
  243. -------       -------
  244.  
  245. CLRSCN        Clear the screen.
  246. SAVECSR       Save the cursor position.
  247. RESTCSR       Restore the cursor postion.
  248. UP(x)         Move the cursor up x rows.
  249. DOWN(x)       Move the cursor down x rows.
  250. RIGHT(x)      Move the cursor right x columns.
  251. LEFT(x)       Move the cursor left x columns.
  252. HOME          Send the cursor home to 1,1.
  253. BLINK         Make subsequent text blink.
  254. REVERSE       Make subsequent text reverse video (dark on light).
  255. NORMAL        Make subsequent text normal video.
  256. GOTOXY(x,y)   Send the cursor to row x and column y.
  257. CLREOL        Clear to end of line.
  258. HIGH          Makes the following color "bright."
  259. RESET         Restores the normal grey on black colors of DOS.
  260. RED           Red foreground.
  261. YELLOW        Yellow foreground.
  262. MAGENTA       Magenta foreground.
  263. WHITE         White foreground.
  264. BLACK         Black foreground.
  265. GREEN         Green foreground.
  266. BLUE          Blue foreground.
  267. CYAN          Cyan foreground.
  268. REDBK         Red background.
  269. YELLOWBK      Yellow background.
  270. MAGENTBK      Magenta background.
  271. WHITEBK       White background.
  272. BLACKBK       Black background.
  273. GREENBK       Green background.
  274. BLUEBK        Blue background.
  275. CYANBK        Cyan background.
  276.  
  277.  Other
  278. Command       Meaning
  279. -------       -------
  280.  
  281. INCLUDE       Include the contents of the file defined by the filename
  282.               immediately following the INCLUDE command.  Succeeding
  283.               text (if any) in the original file is appended to that from
  284.               the include file (if any).  In-line includes are
  285.               supported.  Nested includes are not supported.
  286.  
  287. Example:
  288.  
  289. [INCLUDE  C:\TEXT\SECLEVEL.INC ] would cause the file seclevel.inc to be
  290. included in the output file.  If the file doesn't exist, then the INCLUDE
  291. command is ignored.
  292.  
  293.  
  294. ERRORS:
  295. -------
  296.  
  297. Erroneous embedded or ANSI codes are ignored.  To facilitate debugging, the
  298. code in error is left embedded in the output stream.  A quick scan of the
  299. output file should allow you to find any errors.  If an include file is not
  300. found, then the include command is ignored.
  301.  
  302. THEDRAW screens can be decompiled by RAECU.  However, before they can be
  303. recompiled using RAECC, some hand tuning will be required.  This occurs
  304. because THEDRAW fills each line (255 bytes) with codes.  The decompiled
  305. codes then exceed 255 bytes because the keywords are longer than the codes
  306. they represent.  So, I was forced to include an CR/LF combination to keep
  307. line lengths under 255 bytes.  Sorry about this, and I'll fix it if I can.
  308.  
  309.  
  310. CREDITS:
  311. --------
  312.  
  313. Remote Access is the copyrighted work of somebody!
  314.  
  315. This program is written in Turbo Pascal 5.5, a trademark of Borland           |
  316. International.
  317.  
  318. The idea for this program came from two sources: OECC, the OPUS embedded
  319. command compiler, and QECC, the QuickBBS Embedded Code Compiler produced
  320. by Dave Kerley of Turbo-Soft.  Since then I've produced my own QKECC for
  321. QuickBBS.  This utility is a direct port to the Remote Access BBS software
  322. system.
  323.  
  324. I appreciate the efforts of the beta testers: Mark Howard (Rivendell) and
  325. Mike Janke (Kendal BBS).  Mark Howard suggested the idea of the code
  326. decompiler.  Mark really deserves a lot of credit -- he has served as a
  327. goad, a confidant and as an excellent source of new ideas and improvements.
  328.  
  329.  
  330. BUG REPORTS:
  331. ------------
  332.  
  333. If you find a bug, call my BBS (BrainStorm BBS, 601 798 9477, 12/2400bps,
  334. 23hrs), send me netmail at 1:18/60 or write to me at the above address.
  335.  
  336. Please be sure to include as complete a description of the circumstances
  337. as you can.  A description of your hardware/software configuration will
  338. also be helpful.  Please include the error number and address, i.e.,
  339. RunTime Error ??? at 0000:0000 (you fill in the numbers!), if
  340. appropriate.  I prefer to receive a file containing the text on which the
  341. program bombed so I can reproduce the problem.
  342.  
  343.  
  344. COMMENTS ON MENU DESIGN:
  345. ------------------------
  346.  
  347. When designing screens, I suggest you start out with a mockup.  Use a
  348. text editor (such as QEdit) to do all the layout of your screens, put in
  349. boxes, draw pictures of the menu trees, and so forth.  You should tinker
  350. with these text files until you have a good idea of how you want your
  351. screens to look.
  352.  
  353. Then, WITH A COPY of your basic layout, insert the keywords for colors
  354. and RA commands.  You can use RAECC to compile the screens and then
  355. TYPE them to see how they will look.  For ANSI screens, be sure you have
  356. ANSI.SYS, or one of the excellent replacements, loaded in your config.sys
  357. file.  When you get close to your goal, fire up your menu editor and
  358. create the control portion of your menus.  Fire up RA and take a look
  359. at your results.
  360.  
  361. Be sure to retain your original mockup.  If you don't like the results
  362. of your work, you can go back and modify your original ideas until you
  363. get a set of screens that satisfy you.  Expect to make several trials
  364. before arriving at a finished product.
  365.  
  366. There are a couple of principles you should follow.  First, never leave
  367. the user without a way to the top (or main) menu.  With complicated menu
  368. topologies, it is very easy to lose your way and get frustrated.  If
  369. this happens, your will get a lot of hangups and few frequent callers.
  370.  
  371. Second, show the user the path they used to get to the current menu.  I
  372. use names and arrows to indicate the path at the top left of my screens.
  373. I've seen some very nice trees on a couple of boards; you could use
  374. these too.
  375.  
  376. Third, grouping is important.  Use location to group related commands.
  377. On my main menu (see the example), I've grouped the file, system and
  378. mail commands into thirds of the screen.  That way, the user can find
  379. the command they want and execute it without hunting all over the
  380. screen.
  381.  
  382. Fourth, use mnemonic keys whenever possible.  This aids remembering the
  383. commands and helps limit the amount of time required to execute the
  384. desired function.  The hot keys concept of RA is very attractive (it
  385. is one of my favorite features) because it supports the power user.
  386.  
  387. Fifth, use color to delineate your menus for color callers.  With care,
  388. you can also support your monochrome callers because some colors are
  389. rendered as high intensity on mono screens.
  390.  
  391. It takes some fine tuning the get a menu structure that you like
  392. (believe me, expect to spend some time at it).  With the general
  393. guidelines above, you should be able to construct some fine menus if you
  394. apply yourself.
  395.  
  396.  
  397. QUESTIONS AND COMMENTS:
  398. -----------------------
  399.  
  400. Send your comments, suggestions and compliments to me at the ground
  401. address above or via Fidonet at node 1:18/60.  Save us both time and
  402. aggravation by sending your complaints to NUL.  You are also welcome on
  403. my BBS at 601 798-9477 12/2400bps, 23hrs, 7days.  Zone Mail Hour
  404. (0300-0400 CST) is observed.
  405.  
  406. Finally, you may file request the current version of RAECC from my BBS
  407. anytime except ZMH using the magic filename RAECC.
  408.  
  409.  
  410. HISTORY:
  411. --------
  412.  
  413.  4/15/90 - Version 0.10.  This was the original beta version.  However, it
  414.            should be almost bulletproof as it is a direct port of my QKECC
  415.            utility, which has been in use since June 89.
  416.  
  417.  6/23/90 - Version 0.11.  This is a release implementing new ^K keywords.     |
  418.  
  419.  
  420.  
  421. WHAT'S NEXT?
  422. ------------
  423.  
  424. What should be added next (rhetorical question)?  Well, for starters, I'd
  425. like to add the ability to stack commands inside a set of brackets.  For
  426. instance, [CLS, HIGH, YELLOW] would compile to clear the screen, set the
  427. ANSI color high and use yellow.  I have an idea that will allow recompiling
  428. decompiled THEDRAW screens, provided you don't make too many changes.
  429. Also, I'd like to introduce a shorthand notation for all the attribute
  430. (ANSI) codes, at least, and perhaps for some of the BBS codes as well
  431. (Thanks, Mark!).
  432.  
  433. I could use some suggestions from you who are using the program.  Anything
  434. can and will be considered.  Off-the-wall comments tend to get me thinking,
  435. so they are welcome as well.
  436.  
  437. Dave Thompson
  438.  
  439. <eof>
  440.